

                        ColourTrans Enhancement
                        =======================


Documentation for !CTenhance application, version 2.00 15-Feb-1994, 
                     and CTenhance module version 2.21 07-Aug-1994.

Requires RISC OS 3.1 or later.

Issue: 2.11 07-Aug-1994, replaces:      0.10 31-Mar-1992
                                        1.00 07-Apr-1992
                                        1.30 28-Nov-1992
                                        2.00 16-Feb-1994
                                        2.10 04-Apr-1994
Author: David J Ruck 

Copyright  DEEJ Technology PLC 1992-1994

 

Overview
========

The ColourTrans module is used by many RISC OS applications to represent 24
bit RGB colour values on the limited palette available with the current
Archimedes display system. The CTenhance module (and accompanying RISC OS
front end !CTenhance), is designed to greatly increase the number of colours
which can be represented by the ColourTrans module.

Early versions of ColourTrans work by selecting the closest colour to the
desired 24 bit RGB value, which can be found from the current palette. This
gives a fairly good representation in 256 colour modes, but very poor
results in modes with less colour, especially in two colour modes where only
black or white can be used.

Later versions of ColourTrans supplied with RISC OS 3 now use limited
dithering, allowing a few intermediate shades to be made from patterns of
two  colours. CTenhance can be used to provide an even better quality colour
display by using advanced techniques similar to those in image processing
programs such as !ChangeFSI . 


Dithering
---------
CTenhance vastly increases the number of colours in all modes by using a
technique of error diffused dithering. This technique is used to build a
pattern of colours, which are selected to diffuse the difference (or error)
between the closest colour that could be found and the desired 24 bit
colour.

When viewed the pattern of colours appears to merge producing the desired
colour. A far greater range of colours can be displayed in 256 colour modes,
and a full 256 level grey scale can be produced even in two colour modes.


Compatibility
-------------
!CTenhance will work with all correctly written applications that use the
ColourTrans module, which includes all programs that handle draw files.
Programs do not have to be specially written to take advantage of
!CTenhance, as they do to be able to use the new ColourTrans dithering.

The CTenhance module intercepts the SWI's ColourTrans_SetGCOL and
ColourTrans_SetOppGCOL so that the currently selected graphics colour is set
to a pattern, this is transparent to any application which uses ColourTrans.
Further information is given in the section Technical Details.


Graphics Cards
--------------
CTenhance will function with third party graphics cards which use the legal
RISC OS 3.1 ColourTrans and PaletteV operations, to give a variable 24 bit
palette in 256 colours modes. CTenhance will not work with modes of greater
than 256 colours.



Using !CTenhance
================

A RISC OS front end !CTenhance is provided to easily load the CTenhance
module and to set various parameters, which can be used to get the most
efficient use from the module.

Iconbar menu
------------
Info            Displays a standard program information dialog box.

Parameters      This leads to the Parameters dialogue box which is described
                below.

Quit            This option quits the !CTenhance front end, leaving the
                CTenhance module installed with the current parameter
                settings.

                This can be used when the desired settings have been made,
                and so that the memory used by the front end can be used by
                other applications. The module is small and does not require
                much work space, but the front end is relatively large, as
                is the course for WIMP C programs.

Kill            This will quit the !CTenhance front end and also remove the
                module, restoring the standard operation of ColourTrans.


Parameters Dialogue
-------------------
The parameters dialogue is used to alter settings which adjust the quality
and speed of operation of the CTenhance module. It can be displayed either
from the iconbar menu, or by clicking on the bar-icon, it which case it will
remain on screen allowing different settings to be tried more easily.

OK              Clicking on this button will send the current settings to
                the CTenhance module. Clicking with select will close the
                dialog box, clicking with adjust will cause it to stay on
                screen.

                Closing the dialogue box (via the close icon) will not
                change any of the settings.

Save            This will save the current parameters so that they become
                the default when !CTenhance is next run.

Redraw screen   Clicking on this button will send current settings to the
                CTenhance module and the screen will be redrawn. Any
                applications which use ColourTrans will redraw their windows
                showing the effect of any changes to the parameter values.

ColourTrans Enhance (On/Off)
                This can be used to turn the operation of CTenhance on or 
                off, the current setting is shown in brackets and will not 
                change until OK or Redraw screen is pressed.

Pattern size    The size of pattern used by CTenhance will determine the
                number of additional colours which it is able to display, it
                also determines the speed of operation of the module. A
                value of three should be used for maximum range of colours,
                and one for the maximum speed. For more information see the
                section Technical Details.

Pattern cache   As calculating an error diffused pattern is necessary slower
                than just returning the closest colour, a cache of the
                patterns generated for each 24 bit colour is stored, so that
                when the colour is requested again the time to define it is
                greatly reduced. Setting the number of entries the cache to
                just greater than the estimated number of colour on screen
                will greatly increase the speed of subsequent redraws.



CTenhance with new RISC OS versions
===================================

RISC OS 3.1
-----------
When CTenhance is active all programs will benefit from the ColourTrans
dithering. This includes the desktop where much better results can been seen
in 2 and 4 colour modes. 

Applications which can take advantage of the new ColourTrans module will
also use the much better CTenhance dithering giving results comparable with
graphics enhancer cards in the new multisync & SVGA modes.

Users wishing to use the ColourTrans extended mode, in their own programs,
should use the SWI ColourTrans_SetGCOL with bit 8 set of register R3. See
the Programmers Reference Manuals for more details on how to use this SWI.


RISC OS 3.5
-----------
RISC OS 3.5 together with a machine with suitable hardware is capable of
displaying modes with variable 256 colour palettes and 15 & 24 bit modes.
CTenhance will function correctly with 256 variable palettes in combination
with ColourTrans.

CTenhance automatically disables its self in mode than 8 bits per pixel
modes, it is not required in 24 bit modes (all possible colours can be
displayed without dithering). In 15 bits per pixel only a few dither
patterns are necessary to display the full 24 bits, this can be done by the
limited ColourTrans dithering.



Technical Details
=================

The CTenhance module legally intercepts three SWI's provided by the
ColourTrans module via the ColourV vector, all other operations provided are
unchanged. 

The SWI's ColourTrans_SetGCOL and ColourTrans_SetOppGCOL are intercepted so
that instead of setting the current graphics foreground or background colour
to the nearest match to the 24 bit value, an ECF pattern is defined and the
graphics action set so it is used in subsequent plotting actions. See the
RISC OS Programmer Reference Manuals for more information on extended colour
fill patterns (ECF's).

ColourTrans_InvalidateCache is intercepted and then passed onto the original
ColourTrans routine so that palette changes can be correctly dealt with. The
palette is read using ColourTrans_ReadPalette, which in turn uses PaletteV,
allowing extended 24 bit palettes from graphics card to be read.

The CTenhance module provides two SWI's to control its operation which can
be used in user programs:

        CTenhance_ReadStatus    (number; &49100)
        CTenhance_SetStatus     (number; &49101)

Both SWI's use/return three parameters in R0, R1 & R2, described below:

R0, Status      The status is 0 for CTenhance inactive and 1 for CTenhance
                active. When using CTenhance_Setstatus with R0=0 other
                parameters are ignored, otherwise the current parameters are
                set and returned.

                All RMA workspace used by CTenhance is freed when
                deactivating. Reactivating will fail if workspace cannot be
                claimed from the RMA. The amount required is 5K + 36 bytes
                for each cache entry, e.g. for cache size 256, a total of
                14K.

R1, Pattern size 
                The pattern size determines the the number of pixels in the
                error diffused pattern and hence the speed of operation of
                the SetGCOL SWI's. The Giant ECF pattern type is always used
                with the calculated pattern being repeated within the ECF if
                necessary.

                Values are 1,2,3 increasing in colour range and decreasing
                in speed. 0 can be used for no change, the default is 3.

                +------------------+------------+-------------+-------------+
                | Mode/Size (cols) |     1      |      2      |      3      |
                +------------------+------------+-------------+-------------+
                | 2 colours        | 88 (64)   | 168 (128)  | 328 (256)  |
                | 4 colours        | 48 (128)  | 88  (256)  | 168 (512)  |
                | 16 colours       | 44 (256)  | 48  (512)  | 88  (1024) |
                | 256 colours      | 42 (2048) | 44  (4096) | 48  (8192) |
                +------------------+------------+-------------+-------------+

                CTenhance is highly optimized and uses advanced caching
                techniques for the fastest possible results. Initial drawing
                of windows will be slightly slower than without CTenhance,
                subsequent redraws will be much faster.

                The drawing of colour scales (especially grey scales), used
                in blends and graduated fills has been particularly
                optimized.

R2, Cache Size  The pattern corresponding to a 24 bit colour value is stored
                in a cache so that subsequent calls with the same value will
                execute much faster. The most efficient size is just greater
                than the number of colours used on screen, so all the
                colours are cached making redrawing is much quicker.

                Very large values should be avoided as this will slow down
                cache checking and use a large amount of RMA space. Sensible
                values range from 256 to 2000, use 0 for no change, the
                default is 256.



End of !CTenhance.!Help.

